home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / gcc / gcc261a.zoo / info / gcc.info-5 < prev    next >
Encoding:
GNU Info File  |  1994-10-31  |  21.5 KB  |  470 lines

  1. This is Info file gcc.info, produced by Makeinfo-1.54 from the input
  2. file gcc.texi.
  3.  
  4.    This file documents the use and the internals of the GNU compiler.
  5.  
  6.    Published by the Free Software Foundation 675 Massachusetts Avenue
  7. Cambridge, MA 02139 USA
  8.  
  9.    Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
  10.  
  11.    Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.  
  15.    Permission is granted to copy and distribute modified versions of
  16. this manual under the conditions for verbatim copying, provided also
  17. that the sections entitled "GNU General Public License" and "Protect
  18. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  19. original, and provided that the entire resulting derived work is
  20. distributed under the terms of a permission notice identical to this
  21. one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that the sections entitled "GNU General Public
  26. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  27. permission notice, may be included in translations approved by the Free
  28. Software Foundation instead of in the original English.
  29.  
  30. File: gcc.info,  Node: Installation,  Next: C Extensions,  Prev: Invoking GCC,  Up: Top
  31.  
  32. Installing GNU CC
  33. *****************
  34.  
  35. * Menu:
  36.  
  37. * Configurations::    Configurations Supported by GNU CC.
  38. * Other Dir::     Compiling in a separate directory (not where the source is).
  39. * Cross-Compiler::   Building and installing a cross-compiler.
  40. * Sun Install::   See below for installation on the Sun.
  41. * VMS Install::   See below for installation on VMS.
  42. * Collect2::      How `collect2' works; how it finds `ld'.
  43. * Header Dirs::   Understanding the standard header file directories.
  44.  
  45.    Here is the procedure for installing GNU CC on a Unix system.  See
  46. *Note VMS Install::, for VMS systems.  In this section we assume you
  47. compile in the same directory that contains the source files; see *Note
  48. Other Dir::, to find out how to compile in a separate directory on Unix
  49. systems.
  50.  
  51.    You cannot install GNU C by itself on MSDOS; it will not compile
  52. under any MSDOS compiler except itself.  You need to get the complete
  53. compilation package DJGPP, which includes binaries as well as sources,
  54. and includes all the necessary compilation tools and libraries.
  55.  
  56.   1. If you have built GNU CC previously in the same directory for a
  57.      different target machine, do `make distclean' to delete all files
  58.      that might be invalid.  One of the files this deletes is
  59.      `Makefile'; if `make distclean' complains that `Makefile' does not
  60.      exist, it probably means that the directory is already suitably
  61.      clean.
  62.  
  63.   2. On a System V release 4 system, make sure `/usr/bin' precedes
  64.      `/usr/ucb' in `PATH'.  The `cc' command in `/usr/ucb' uses
  65.      libraries which have bugs.
  66.  
  67.   3. Specify the host and target machine configurations.  You do this by
  68.      running the file `configure' with appropriate arguments.
  69.  
  70.      The `configure' script searches subdirectories of the source
  71.      directory for other compilers that are to be integrated into GNU
  72.      CC.  The GNU compiler for C++, called G++ is in a subdirectory
  73.      named `cp'.  `configure' inserts rules into `Makefile' to build
  74.      all of those compilers.
  75.  
  76.      If you are building a compiler to produce code for the machine it
  77.      runs on, specify the "configuration name" with the `--target'
  78.      option; the host will default to be the same as the target.  (If
  79.      you are building a cross-compiler, see *Note Cross-Compiler::.)
  80.  
  81.      Here is an example:
  82.  
  83.           ./configure --target=sparc-sun-sunos4.1
  84.  
  85.      If you run `configure' without specifying configuration arguments,
  86.      `configure' tries to guess the type of host you are on, and uses
  87.      that configuration type for both host and target.  So you don't
  88.      need to specify a configuration, for building a native compiler,
  89.      unless `configure' cannot figure out what your configuration is.
  90.  
  91.      A configuration name may be canonical or it may be more or less
  92.      abbreviated.
  93.  
  94.      A canonical configuration name has three parts, separated by
  95.      dashes.  It looks like this: `CPU-COMPANY-SYSTEM'.  (The three
  96.      parts may themselves contain dashes; `configure' can figure out
  97.      which dashes serve which purpose.)  For example,
  98.      `m68k-sun-sunos4.1' specifies a Sun 3.
  99.  
  100.      You can also replace parts of the configuration by nicknames or
  101.      aliases.  For example, `sun3' stands for `m68k-sun', so
  102.      `sun3-sunos4.1' is another way to specify a Sun 3.  You can also
  103.      use simply `sun3-sunos', since the version of SunOS is assumed by
  104.      default to be version 4.  `sun3-bsd' also works, since `configure'
  105.      knows that the only BSD variant on a Sun 3 is SunOS.
  106.  
  107.      You can specify a version number after any of the system types,
  108.      and some of the CPU types.  In most cases, the version is
  109.      irrelevant, and will be ignored.  So you might as well specify the
  110.      version if you know it.
  111.  
  112.      See *Note Configurations::, for a list of supported configuration
  113.      names and notes on many of the configurations.  You should check
  114.      the notes in that section before proceding any further with the
  115.      installation of GNU CC.
  116.  
  117.      There are four additional options you can specify independently to
  118.      describe variant hardware and software configurations.  These are
  119.      `--with-gnu-as', `--with-gnu-ld', `--with-stabs' and `--nfp'.
  120.  
  121.     `--with-gnu-as'
  122.           If you will use GNU CC with the GNU assembler (GAS), you
  123.           should declare this by using the `--with-gnu-as' option when
  124.           you run `configure'.
  125.  
  126.           Using this option does not install GAS.  It only modifies the
  127.           output of GNU CC to work with GAS.  Building and installing
  128.           GAS is up to you.
  129.  
  130.           Conversely, if you *do not* wish to use GAS and do not specify
  131.           `--with-gnu-as' when building GNU CC, it is up to you to make
  132.           sure that GAS is not installed.  GNU CC searches for a
  133.           program named `as' in various directories; if the program it
  134.           finds is GAS, then it runs GAS.  If you are not sure where
  135.           GNU CC finds the assembler it is using, try specifying `-v'
  136.           when you run it.
  137.  
  138.           The systems where it makes a difference whether you use GAS
  139.           are
  140.           `hppa1.0-ANY-ANY', `hppa1.1-ANY-ANY', `i386-ANY-sysv',
  141.           `i386-ANY-isc',
  142.           `i860-ANY-bsd', `m68k-bull-sysv', `m68k-hp-hpux',
  143.           `m68k-sony-bsd',
  144.           `m68k-altos-sysv', `m68000-hp-hpux', `m68000-att-sysv', and
  145.           `mips-ANY').  On any other system, `--with-gnu-as' has no
  146.           effect.
  147.  
  148.           On the systems listed above (except for the HP-PA and for ISC
  149.           on the 386), if you use GAS, you should also use the GNU
  150.           linker (and specify `--with-gnu-ld').
  151.  
  152.     `--with-gnu-ld'
  153.           Specify the option `--with-gnu-ld' if you plan to use the GNU
  154.           linker with GNU CC.
  155.  
  156.           This option does not cause the GNU linker to be installed; it
  157.           just modifies the behavior of GNU CC to work with the GNU
  158.           linker.  Specifically, it inhibits the installation of
  159.           `collect2', a program which otherwise serves as a front-end
  160.           for the system's linker on most configurations.
  161.  
  162.     `--with-stabs'
  163.           On MIPS based systems and on Alphas, you must specify whether
  164.           you want GNU CC to create the normal ECOFF debugging format,
  165.           or to use BSD-style stabs passed through the ECOFF symbol
  166.           table.  The normal ECOFF debug format cannot fully handle
  167.           languages other than C.  BSD stabs format can handle other
  168.           languages, but it only works with the GNU debugger GDB.
  169.  
  170.           Normally, GNU CC uses the ECOFF debugging format by default;
  171.           if you prefer BSD stabs, specify `--with-stabs' when you
  172.           configure GNU CC.
  173.  
  174.           No matter which default you choose when you configure GNU CC,
  175.           the user can use the `-gcoff' and `-gstabs+' options to
  176.           specify explicitly the debug format for a particular
  177.           compilation.
  178.  
  179.           `--with-stabs' is meaningful on the ISC system on the 386,
  180.           also, if `--with-gas' is used.  It selects use of stabs
  181.           debugging information embedded in COFF output.  This kind of
  182.           debugging information supports C++ well; ordinary COFF
  183.           debugging information does not.
  184.  
  185.     `--nfp'
  186.           On certain systems, you must specify whether the machine has
  187.           a floating point unit.  These systems include
  188.           `m68k-sun-sunosN' and `m68k-isi-bsd'.  On any other system,
  189.           `--nfp' currently has no effect, though perhaps there are
  190.           other systems where it could usefully make a difference.
  191.  
  192.      Here we spell out what files will be set up by `configure'.
  193.      Normally you need not be concerned with these files.
  194.  
  195.         * A symbolic link named `config.h' is made to the top-level
  196.           config file for the machine you will run the compiler on
  197.           (*note Config::.).  This file is responsible for defining
  198.           information about the host machine.  It includes `tm.h'.
  199.  
  200.           The top-level config file is located in the subdirectory
  201.           `config'.  Its name is always `xm-SOMETHING.h'; usually
  202.           `xm-MACHINE.h', but there are some exceptions.
  203.  
  204.           If your system does not support symbolic links, you might
  205.           want to set up `config.h' to contain a `#include' command
  206.           which refers to the appropriate file.
  207.  
  208.         * A symbolic link named `tconfig.h' is made to the top-level
  209.           config file for your target machine.  This is used for
  210.           compiling certain programs to run on that machine.
  211.  
  212.         * A symbolic link named `tm.h' is made to the
  213.           machine-description macro file for your target machine.  It
  214.           should be in the subdirectory `config' and its name is often
  215.           `MACHINE.h'.
  216.  
  217.         * A symbolic link named `md' will be made to the machine
  218.           description pattern file.  It should be in the `config'
  219.           subdirectory and its name should be `MACHINE.md'; but MACHINE
  220.           is often not the same as the name used in the `tm.h' file
  221.           because the `md' files are more general.
  222.  
  223.         * A symbolic link named `aux-output.c' will be made to the
  224.           output subroutine file for your machine.  It should be in the
  225.           `config' subdirectory and its name should be `MACHINE.c'.
  226.  
  227.         * The command file `configure' also constructs the file
  228.           `Makefile' by adding some text to the template file
  229.           `Makefile.in'.  The additional text comes from files in the
  230.           `config' directory, named `t-TARGET' and `x-HOST'.  If these
  231.           files do not exist, it means nothing needs to be added for a
  232.           given target or host.
  233.  
  234.   4. The standard directory for installing GNU CC is `/usr/local/lib'.
  235.      If you want to install its files somewhere else, specify
  236.      `--prefix=DIR' when you run `configure'.  Here DIR is a directory
  237.      name to use instead of `/usr/local' for all purposes with one
  238.      exception: the directory `/usr/local/include' is searched for
  239.      header files no matter where you install the compiler.  To override
  240.      this name, use thge `--local-prefix' option below.
  241.  
  242.   5. Specify `--local-prefix=DIR' if you want the compiler to search
  243.      directory `DIR/include' for header files *instead* of
  244.      `/usr/local/include'.  (This is for systems that have different
  245.      conventions for where to put site-specific things.)
  246.  
  247.      Unless you have a convention other than `/usr/local' for
  248.      site-specific files, it is a bad idea to specify `--local-prefix'.
  249.  
  250.   6. Make sure the Bison parser generator is installed.  (This is
  251.      unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
  252.      more recent than `c-parse.y' and `cexp.y' and you do not plan to
  253.      change the `.y' files.)
  254.  
  255.      Bison versions older than Sept 8, 1988 will produce incorrect
  256.      output for `c-parse.c'.
  257.  
  258.   7. If you have chosen a configuration for GNU CC which requires other
  259.      GNU tools (such as GAS or the GNU linker) instead of the standard
  260.      system tools, install the required tools in the build directory
  261.      under the names `as', `ld' or whatever is appropriate.  This will
  262.      enable the compiler to find the proper tools for compilation of
  263.      the program `enquire'.
  264.  
  265.      Alternatively, you can do subsequent compilation using a value of
  266.      the `PATH' environment variable such that the necessary GNU tools
  267.      come before the standard system tools.
  268.  
  269.   8. Build the compiler.  Just type `make LANGUAGES=c' in the compiler
  270.      directory.
  271.  
  272.      `LANGUAGES=c' specifies that only the C compiler should be
  273.      compiled.  The makefile normally builds compilers for all the
  274.      supported languages; currently, C, C++ and Objective C.  However,
  275.      C is the only language that is sure to work when you build with
  276.      other non-GNU C compilers.  In addition, building anything but C
  277.      at this stage is a waste of time.
  278.  
  279.      In general, you can specify the languages to build by typing the
  280.      argument `LANGUAGES="LIST"', where LIST is one or more words from
  281.      the list `c', `c++', and `objective-c'.  If you have any
  282.      additional GNU compilers as subdirectories of the GNU CC source
  283.      directory, you may also specify their names in this list.
  284.  
  285.      Ignore any warnings you may see about "statement not reached" in
  286.      `insn-emit.c'; they are normal.  Also, warnings about "unknown
  287.      escape sequence" are normal in `genopinit.c' and perhaps some
  288.      other files.  Likewise, you should ignore warnings about "constant
  289.      is so large that it is unsigned" in `insn-emit.c' and
  290.      `insn-recog.c'.  Any other compilation errors may represent bugs in
  291.      the port to your machine or operating system, and should be
  292.      investigated and reported (*note Bugs::.).
  293.  
  294.      Some commercial compilers fail to compile GNU CC because they have
  295.      bugs or limitations.  For example, the Microsoft compiler is said
  296.      to run out of macro space.  Some Ultrix compilers run out of
  297.      expression space; then you need to break up the statement where
  298.      the problem happens.
  299.  
  300.      If you are building with a previous GNU C compiler, do not use
  301.      `CC=gcc' on the make command or by editing the Makefile.  Instead,
  302.      use a full pathname to specify the compiler, such as
  303.      `CC=/usr/local/bin/gcc'.  This is because make might execute the
  304.      `gcc' in the current directory before all of the compiler
  305.      components have been built.
  306.  
  307.   9. If you are building a cross-compiler, stop here.  *Note
  308.      Cross-Compiler::.
  309.  
  310.  10. Move the first-stage object files and executables into a
  311.      subdirectory with this command:
  312.  
  313.           make stage1
  314.  
  315.      The files are moved into a subdirectory named `stage1'.  Once
  316.      installation is complete, you may wish to delete these files with
  317.      `rm -r stage1'.
  318.  
  319.  11. If you have chosen a configuration for GNU CC which requires other
  320.      GNU tools (such as GAS or the GNU linker) instead of the standard
  321.      system tools, install the required tools in the `stage1'
  322.      subdirectory under the names `as', `ld' or whatever is
  323.      appropriate.  This will enable the stage 1 compiler to find the
  324.      proper tools in the following stage.
  325.  
  326.      Alternatively, you can do subsequent compilation using a value of
  327.      the `PATH' environment variable such that the necessary GNU tools
  328.      come before the standard system tools.
  329.  
  330.  12. Recompile the compiler with itself, with this command:
  331.  
  332.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O"
  333.  
  334.      This is called making the stage 2 compiler.
  335.  
  336.      The command shown above builds compilers for all the supported
  337.      languages.  If you don't want them all, you can specify the
  338.      languages to build by typing the argument `LANGUAGES="LIST"'.  LIST
  339.      should contain one or more words from the list `c', `c++',
  340.      `objective-c', and `proto'.  Separate the words with spaces.
  341.      `proto' stands for the programs `protoize' and `unprotoize'; they
  342.      are not a separate language, but you use `LANGUAGES' to enable or
  343.      disable their installation.
  344.  
  345.      If you are going to build the stage 3 compiler, then you might
  346.      want to build only the C language in stage 2.
  347.  
  348.      Once you have built the stage 2 compiler, if you are short of disk
  349.      space, you can delete the subdirectory `stage1'.
  350.  
  351.      On a 68000 or 68020 system lacking floating point hardware, unless
  352.      you have selected a `tm.h' file that expects by default that there
  353.      is no such hardware, do this instead:
  354.  
  355.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O -msoft-float"
  356.  
  357.  13. If you wish to test the compiler by compiling it with itself one
  358.      more time, install any other necessary GNU tools (such as GAS or
  359.      the GNU linker) in the `stage2' subdirectory as you did in the
  360.      `stage1' subdirectory, then do this:
  361.  
  362.           make stage2
  363.           make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  364.  
  365.      This is called making the stage 3 compiler.  Aside from the `-B'
  366.      option, the compiler options should be the same as when you made
  367.      the stage 2 compiler.  But the `LANGUAGES' option need not be the
  368.      same.  The command shown above builds compilers for all the
  369.      supported languages; if you don't want them all, you can specify
  370.      the languages to build by typing the argument `LANGUAGES="LIST"',
  371.      as described above.
  372.  
  373.      If you do not have to install any additional GNU tools, you may
  374.      use the command
  375.  
  376.           make bootstrap LANGUAGES=LANGUAGE-LIST BOOT_CFLAGS=OPTION-LIST
  377.  
  378.      instead of making `stage1', `stage2', and performing the two
  379.      compiler builds.
  380.  
  381.  14. Then compare the latest object files with the stage 2 object
  382.      files--they ought to be identical, aside from time stamps (if any).
  383.  
  384.      On some systems, meaningful comparison of object files is
  385.      impossible; they always appear "different."  This is currently
  386.      true on Solaris and probably on all systems that use ELF object
  387.      file format.  On some versions of Irix on SGI machines and OSF/1
  388.      on Alpha systems, you will not be able to compare the files
  389.      without specifying `-save-temps'; see the description of
  390.      individual systems above to see if you get comparison failures.
  391.      You may have similar problems on other systems.
  392.  
  393.      Use this command to compare the files:
  394.  
  395.           make compare
  396.  
  397.      This will mention any object files that differ between stage 2 and
  398.      stage 3.  Any difference, no matter how innocuous, indicates that
  399.      the stage 2 compiler has compiled GNU CC incorrectly, and is
  400.      therefore a potentially serious bug which you should investigate
  401.      and report (*note Bugs::.).
  402.  
  403.      If your system does not put time stamps in the object files, then
  404.      this is a faster way to compare them (using the Bourne shell):
  405.  
  406.           for file in *.o; do
  407.           cmp $file stage2/$file
  408.           done
  409.  
  410.      If you have built the compiler with the `-mno-mips-tfile' option on
  411.      MIPS machines, you will not be able to compare the files.
  412.  
  413.  15. Build the Objective C library (if you have built the Objective C
  414.      compiler).  Here is the command to do this:
  415.  
  416.           make objc-runtime CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  417.  
  418.  16. Install the compiler driver, the compiler's passes and run-time
  419.      support with `make install'.  Use the same value for `CC',
  420.      `CFLAGS' and `LANGUAGES' that you used when compiling the files
  421.      that are being installed.  One reason this is necessary is that
  422.      some versions of Make have bugs and recompile files gratuitously
  423.      when you do this step.  If you use the same variable values, those
  424.      files will be recompiled properly.
  425.  
  426.      For example, if you have built the stage 2 compiler, you can use
  427.      the following command:
  428.  
  429.           make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="LIST"
  430.  
  431.      This copies the files `cc1', `cpp' and `libgcc.a' to files `cc1',
  432.      `cpp' and `libgcc.a' in the directory
  433.      `/usr/local/lib/gcc-lib/TARGET/VERSION', which is where the
  434.      compiler driver program looks for them.  Here TARGET is the target
  435.      machine type specified when you ran `configure', and VERSION is
  436.      the version number of GNU CC.  This naming scheme permits various
  437.      versions and/or cross-compilers to coexist.
  438.  
  439.      This also copies the driver program `xgcc' into
  440.      `/usr/local/bin/gcc', so that it appears in typical execution
  441.      search paths.
  442.  
  443.      On some systems, this command causes recompilation of some files.
  444.      This is usually due to bugs in `make'.  You should either ignore
  445.      this problem, or use GNU Make.
  446.  
  447.      *Warning: there is a bug in `alloca' in the Sun library.  To avoid
  448.      this bug, be sure to install the executables of GNU CC that were
  449.      compiled by GNU CC.  (That is, the executables from stage 2 or 3,
  450.      not stage 1.)  They use `alloca' as a built-in function and never
  451.      the one in the library.*
  452.  
  453.      (It is usually better to install GNU CC executables from stage 2
  454.      or 3, since they usually run faster than the ones compiled with
  455.      some other compiler.)
  456.  
  457.  17. Install the Objective C library (if you are installing the
  458.      Objective C compiler).  Here is the command to do this:
  459.  
  460.           make install-libobjc CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  461.  
  462.  18. If you're going to use C++, it's likely that you need to also
  463.      install the libg++ distribution.  It should be available from the
  464.      same place where you got the GNU C distribution.  Just as GNU C
  465.      does not distribute a C runtime library, it also does not include
  466.      a C++ run-time library.  All I/O functionality, special class
  467.      libraries, etc., are available in the libg++ distribution.
  468.  
  469.